feat(install): load the installed pack's operator .env in emitted MCP entries, hook wrappers, and the artifact CLI (#469) - #538

Fixes #469.

Why

Only agent-bundle mcp run composed manifest env < .env files < process.env; hosts launch installed packs directly, so a credential-configured plugin shipped a wrapper script (movie-library's scripts/run-stdio.sh), pointed its installers at it, and re-read <plugin root>/.env by hand in scripts.

Design

• Plain-Node loader, inlined — new packages/agent-bundle/src/launch-env.ts, published as agent-bundle/launch-env (package export, Rslib entry, TypeDoc). No framework or Effect import: applyOperatorEnv({ pluginRoot }) reads <plugin root>/.env then .env.local (or the files AGENT_BUNDLE_ENV_FILE names — platform-delimited list; none disables the layer), fills only variables the host did not set (host env and manifest env win; .env.local beats .env), never logs a value, treats a missing file as the normal case and an unreadable one as skipped, never fatal. parseOperatorEnv is a dotenv subset with no ${VAR} interpolation (documented). operatorEnvPluginRoot(fallback) applies the same anchor precedence as the durable-state kernel — an expanded AGENT_BUNDLE_PLUGIN_ROOT, else the shell's parent directory — spelled without a runtime import so the shells stay small.
• Where it runs — the stdio MCP entry shell of a factory-exporting server (before the deferred server import, so module-level process.env reads see the layer; a self-connecting entry has no shell and reads none unless it calls applyOperatorEnv itself — documented), every config hook wrapper (Claude/Codex/Universal and Cursor codecs) and every event-route wrapper that can render standalone (shared-runtime-only wrappers forward to the warm MCP process, which applied the layer itself), and the artifact-hosted CLI bin/<name>.mjs (before the state owner opens; its render worker inherits). The npm package bin runs from the operator's own shell and reads none. Route modules of hook wrappers and the CLI are static imports, so an import-time process.env read sees the host env only — documented on the installation page.
• mcp run stays byte-faithful — under mcp run the plugin root is the project root, so the shell's pass re-reads the files mcp run already composed: a no-op. --env-file / --no-env are handed down as AGENT_BUNDLE_ENV_FILE (services/mcp-run.ts) so the shell follows the operator's choice.
• Doctor — inspectOperatorEnv reports .env / .env.local presence and variable count per installed copy and --from bundle (DoctorFinding.operatorEnv, human output operator env: …), new AB7331 (info; warning when unreadable). Never a name or a value.
• Bundling — agent-bundle/launch-env is aliased into MCP entries, hook wrappers, and CLI bins (entries.ts, cli-bins.ts, inspect-bundler.ts) and excluded from authored-source evidence. The shell helpers (launch-env-shell.ts) hold only the specifier and emitted lines; launchEnvRuntimePath lives in entry-shell.ts because the hook contract also reaches the installer bundle, which a consumer's Rspack re-bundles — a new URL(…, import.meta.url) probe there breaks the consumer build (found by the packed proof).

Tests

• tests/launch-env.test.ts — grammar, anchor precedence, file list (AGENT_BUNDLE_ENV_FILE, none), fill-gaps semantics, .env.local over .env, absent and unreadable files, no value in the report; inline comments after a closing quote; Windows case-insensitive reservation; a configured root resolved as written.
• tests/hooks.test.ts — real built Claude and Codex wrappers run under node: no file → host env only; <plugin root>/.env fills a gap while an exported variable wins; AGENT_BUNDLE_PLUGIN_ROOT relocates the file; explicit AGENT_BUNDLE_ENV_FILE; none.
• tests/packed-stdio-projection.test.ts — the real packed stdio server (openPackedMcpServer): an env-probe tool added to the packed copy observes .env and .env.local values, the host's exported variable untouched, an absent name null; nothing sensitive on stderr. pnpm test:packed for this file passes locally.
• tests/package-build.test.ts — mcp run hands AGENT_BUNDLE_ENV_FILE down for --env-file and --no-env, not for the bare run.
• tests/doctor.test.ts — AB7331 with counts only; absent files produce no diagnostic; human output.
• tests/entry-shell.test.ts — layer before the deferred import in the stdio shell; artifact bin applies it, durable bin imports fileURLToPath once, npm bin never.

Docs

docs/diagnostics.md (AB7331), docs/entry-conventions.md (launch environment; self-connecting exclusion), website/docs/{en,zh}/guide/distribution/installation.mdx (new "Operator configuration" section with the precedence table), website/docs/{en,zh}/reference/runtime-environment.mdx (AGENT_BUNDLE_ENV_FILE, new section), website/docs/{en,zh}/reference/api.mdx, website/docs/{en,zh}/guide/authoring/mcp.mdx (self-connecting entries: no shell, no layer; call applyOperatorEnv yourself). pnpm docs:site:build green.

Verification

pnpm typecheck, pnpm lint, pnpm test:unit (3262 passed), integration hooks.test.ts + package-build.test.ts, packed packed-stdio-projection.test.ts, pnpm docs:site:build.

Review status

No PR comments are posted from this side; review threads are answered in this section and in code.

• Codex reviewed daf1999ce (PR opened), three P2 threads — all addressed in the landing commit (fix(launch-env): …):
  • build/entries.ts — self-connecting stdio entries get no loader. Correct: a self-connecting entry has no lifecycle shell (it keeps its byte-identical body, AB4730 nudge only), so there is no place to apply a layer before its own top-level code runs, and the exclusion is documented (mcp.mdx en+zh "Handwritten stdio entries", installation.mdx en+zh, docs/entry-conventions.md, the changeset). The documented recipe — the entry imports agent-bundle/launch-env and calls applyOperatorEnv itself — had a hole, though: the alias existed only for wrapped entries, so the import resolved only through the plugin's own node_modules (a project without it failed with Can't resolve 'agent-bundle/launch-env'). Fixed in ab9818aa7: planMcpEntriesSurface and the inspect --bundler mirror alias agent-bundle/launch-env into every stdio entry (inlined only where imported, excluded from authored-source evidence, reserved against externalization), the docs show the full recipe with operatorEnvPluginRoot, and a new mcp.test.ts case builds such an entry and runs it under node against <plugin root>/.env.
  • launch-env.ts — TOKEN="secret" # note read as an open multi-line value. Fixed: the parser finds the first unescaped closing quote (continuing onto later lines for "/' only while it is still open), accepts only whitespace or a # comment after it, and otherwise falls back to dotenv's unquoted reading of the line (quotes kept). Pinned by a new parseOperatorEnv case (double, single, backtick, escaped quote, non-comment trailer, unterminated at EOF).
  • launch-env.ts — Windows env keys are case-insensitive. Fixed: applyOperatorEnv normalises reserved and parsed keys with toUpperCase() when platform (new option, default process.platform) is win32, so a host Path reserves PATH. Pinned by a test that runs the same file under win32 and linux.
• Also aligned with feat(runtime): expose the resolved plugin root as request.plugin and hand it to providers (#468) #532's review fix (same finding on resolvePluginRoot): operatorEnvPluginRoot trims only for the blank check and resolves a configured AGENT_BUNDLE_PLUGIN_ROOT exactly as written, so the operator files and the durable-state kernel anchor on one directory.

Landing notes (rebase over main after #532, #526, #540, #545)

• feat(runtime): expose the resolved plugin root as request.plugin and hand it to providers (#468) #532 made every generated module declare pluginRoot once; the artifact CLI bin now emits operatorEnvImports({ importsFileUrlToPath: true }) because the #468 artifact imports already bind fileURLToPath (the entry-shell.test.ts "imports fileURLToPath once" pin holds). mcp-run.ts (refactored by feat(cli): serve a built MCP App standalone — agent-bundle serve-app and serveApp in agent-bundle/api (#514) #537 into resolveMcpLaunchEnvironment) layers the AGENT_BUNDLE_ENV_FILE hand-down between the .env layer and the inherited process.env, for mcp run and serve-app alike.

• Artifact footprint, measured on examples/host-test (main + feat(runtime): expose the resolved plugin root as request.plugin and hand it to providers (#468) #532 baseline vs this branch, same toolchain): every hook wrapper, MCP entry, and artifact bin grows by the inlined loader — ≈ 4.5 KB per hook wrapper and per self-hosted MCP entry, ≈ 4.7 KB per artifact bin, ≈ 7.7 KB for the generated-route MCP entry; Flight workers +70 B. The loader carries no Effect import; the set of artifact files referencing Effect is identical before and after (the host-test event-route wrappers already bundle the runtime), and the hand-rolled mcp-host-test-raw entry references none in either build.

• Re-verified after the rebase: pnpm build, pnpm typecheck, pnpm lint, unit (launch-env, entry-shell, doctor, public-api), integration (hooks, package-build), pnpm docs:site:build.

• CI on the rebased head failed hook-handler-contract.test.ts: the test evaluates a wrapper's codec internals from a temp file, and the wrapper now imports agent-bundle/launch-env at the top level, which the temp file cannot resolve. Fixed in 93584ef by stripping that import and the applyOperatorEnv statement from the evaluated slice (the codec under test needs neither). Full pnpm test:unit green afterwards (3339 passed).

• ab9818aa7, on the branch updated over main with feat(lineage): expose the live agent tree (siblings, children, roots) on request.lineage (#457) #544 and feat(mcp): serve task-augmented tool calls — CreateTaskResult, tasks/get, tasks/result, tasks/cancel, tasks/list (#369) #550: pnpm build, pnpm typecheck, pnpm lint, pnpm test:unit (3353 passed), integration mcp, build, hooks, package-build, emitted-artifact-effect-surface (97 passed), pnpm docs:site:build.

Self-review

Reviewer: gpt-5.6-sol-medium (change-risk-reviewer), run against the diff vs origin/main before merge.

Findings:

1. Precedence is wrong for installed MCP entries. Manifest env beats .env, contrary to the documented manifest < .env < process.env: launch-env.ts reserves every pre-existing process.env key, and hosts merge the manifest env block into the child environment before launch, so the child cannot tell inherited host variables from manifest defaults.
2. Hook and CLI static imports run before .env is applied. ESM evaluates static imports before the wrapper's operatorEnvStatement, so import-time process.env reads in hook handlers and CLI route/provider modules never see the operator .env; hook coverage only read process.env inside the handler.

Disposition: both fixed in follow-up, folded into #554 (branch fix/469-followup-env-precedence, commit c71431851). The emitted stdio entry embeds the server's manifest env block and applyOperatorEnv takes it as manifestEnv, reserving a present variable only when its value differs from the embedded default; the layer became a generated virtual module (agent-bundle/launch-env-layer) that every stdio entry, hook wrapper, and artifact CLI bin imports first, ahead of the server, handler, route, provider, and state modules. Host manifests are unchanged.

No findings in: path traversal / secrets in diagnostics; Windows/POSIX behaviour; regressions for existing installs; docs + changeset consistency.